home *** CD-ROM | disk | FTP | other *** search
/ Technotools / Technotools (Chestnut CD-ROM)(1993).ISO / lang_c / ctb100t / manual.asc < prev    next >
Text File  |  1987-08-28  |  40KB  |  1,312 lines
  1.  
  2.  
  3.  
  4.                            C Tool Box
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.                    A Library of Functions for
  19.                           Turbo C 1.00
  20.  
  21.                    Containing Graphics, Fonts,
  22.                 Windows, Sound, Background Sound
  23.               Mouse, Joystick and Printer Controls
  24.                             and more
  25.  
  26.  
  27.  
  28.  
  29.                          Version 1.00 
  30.                    release date 22 August 1987
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.                        Copyright (c) 1987
  42.                                by
  43.                         David A.  Miller
  44.                         Unicorn Software
  45.                         8018 NE 123rd St.
  46.                        Kirkland, WA 98034
  47.                   (206) 823-4656 after 6:30 PM
  48.                         Pacific Time Zone
  49.                     (No collect calls Please)
  50.  
  51.  
  52.  
  53.  
  54.  
  55. Welcome  to the realm of the mystical Unicorn.   It has  been  an 
  56. enjoyable  process creating this library and the author hopes you 
  57. find it equally enjoyable to use.
  58.  
  59.  
  60.  
  61.  
  62.                            Disclaimer
  63.  
  64. The author has taken due care in the preparation of this manual 
  65. and the associated programs to insure that all information 
  66. presented is correct and functional as stated.  No warranty is 
  67. made regarding the suitability of this product for any specific 
  68. purpose.  Consistent with the requirement of speed in much of 
  69. the library and the general philosophy of C in allowing the 
  70. programmer complete freedom, the amount of error checking has 
  71. been held to a minimum.
  72.  
  73.   The author hereby grants permission to all users to transfer 
  74. copies of the library to third parties subject to the conditions 
  75. that the entire library and all files including copyrights be 
  76. transferred in full for no fee execept in the case of users groups 
  77. which may charge a copying fee not to exceed $7.00.
  78.  
  79.   While you may use the library for personal programs without 
  80. registration, those who create programs for sale or distribution 
  81. are requested to register their copy.  The source code may NOT be 
  82. distributed to a third party in any form without the written 
  83. permission of the author.
  84.  
  85.  
  86.  
  87.  
  88.  
  89.  
  90. Turbo C is a trademark of Borland International, Microsoft C, 
  91. MASM and MSDOS are trademarks of Microsoft Corp.  IBM, IBM PC, 
  92. PC XT, AT, DOS and PCDOS are trademarks of International Business 
  93. Machines Corp., Epson is a trademark of Epson Corp. Tandy, Tandy 
  94. 1000 A and DMP 130 are trademarks of Tandy Corp.
  95.  
  96.                            Background
  97.  
  98.  
  99.    This library is the successor to the original Unicorn Library 
  100. which has undergone several revisions and essentially has become 
  101. a new entity.  Some of the current revisions concern simple 
  102. ordering of the parameters in calls to make the library more 
  103. consistent.  Users of the Unicorn library should take particular 
  104. note of this point.  Functions have been developed for which the 
  105. author has no specific need but found interesting to implement.  
  106. Many of the functions are a result of user suggestions for which 
  107. we thank the users involved.  The author invites users to make 
  108. further suggestions, as a worthwile challenge is always an 
  109. interesting learning experience.
  110.    
  111.    This library contains functions to perform a wide variety of 
  112. tasks  The functions may be divided roughly into the following 
  113. categories:
  114.  
  115. 1.  General video including windows and fast string writes.
  116. 2.  Graphics, including a variety of normal and rotated fonts
  117. 3.  Sound including background sound functions similar to BASIC
  118. 4.  General functions serving a wide variety of purposes
  119. 5.  Printer control, both graphics and daisy wheel
  120. 6.  Mouse control
  121. 7.  Joystick control
  122.   
  123.    Each of these groupings overlaps to some extent but in general 
  124. all, except the graphics in group 2, may be used with a 
  125. monochrome system. The general library is designed to be used 
  126. with Turbo C from Borland and programs written using the small 
  127. memory model.  Other compilers are supported and libraries may be 
  128. requested from the author upon registration.  In addition to this 
  129. basic library, those available include the large model for Turbo 
  130. C and both models for Microsoft C ( Current version ).  The 
  131. author will also make a Lattice C version 3.0 library available 
  132. if there are enough requests.  While these are the basic 
  133. compilers the author has access to, others may be supported if 
  134. the number of requests warrant.
  135.  
  136.   The entire manual is not supplied with the Bulletin Board 
  137. version of the library due to space.  Enough of the manual is 
  138. included to make the library usable including a brief description 
  139. of each function and a call in a form similar to function 
  140. prototyping.  The entire manual is available on disk in Wordstar 
  141. or ASCII text format and will be sent to all registered owners 
  142. (please specify which format).  Preprinted manuals are available 
  143. for those who don't wish to print over 200 pages.  See the 
  144. registration form for details.  
  145.                        First Things First
  146.  
  147.  
  148. If you have registered your library and have the full source 
  149. distribution disks, you should have one disk of C source code and 
  150. headers, one of ASM source code and either a disk containing the 
  151. manual or the preprinted manual.
  152.  
  153. Check your disks to insure that all files are readable.  There 
  154. should be 14 C source files, 14 ASM source files and 3 header 
  155. files as of this writing.  This amounts to over 500K of source 
  156. code.  
  157.  
  158. There is no particular installation process for this library.  It 
  159. is ready to use as is.  Simply place the library in the directory 
  160. with the other libraries you use with your compiler.
  161.  
  162. Many of the critical functions have been coded in assembler for 
  163. speed.  Some of the present functions coded in C (the fonts 
  164. remaining in C and rotated fonts in particular) will be coded in 
  165. assembler in future revisions.  There are a few instances where 
  166. functions perform similar tasks but are coded differently.  For 
  167. example, there is both an assembler and a C function to set the 
  168. video mode.  Some of these have been left as learning tools for 
  169. the user as they illustrate both approaches to solution of a 
  170. particular task.  Since this library was begun as a learning 
  171. project, it is felt the user may benefit from such material.  
  172.  
  173. Make a backup copy before you do anything else.  The disks are 
  174. not copy-protected in any manner.  Also, it would be helpful if 
  175. you read the file READ.ME as it contains the latest information 
  176. concerning the library.  Where this manual and READ.ME conflict, 
  177. please regard the READ.ME file as being the most current 
  178. information.  
  179.  
  180. There are demo programs on the disk, the largest being CTDEMO.EXE 
  181. and CTDEMO.C.  This was compiled with the library on the 
  182. distribution disks and illustrates the capability of the library 
  183. itself although it by no means uses or illustrates every function 
  184. in the library.
  185.  
  186. The library, as delivered normally, is the small memory model of 
  187. Turbo C, and all references, unless otherwise stated, will refer 
  188. to that configuration.
  189.  
  190. There are over 200 functions contained within the C Tool Box and 
  191. there is a short reference section giving a brief sample call and 
  192. description of each function later in the manual.  The 
  193. comprehensive section following that gives a complete call, 
  194. parameter description, sample program or code fragment 
  195. illustrating the fuctions usage, returns and any caveats that may 
  196. occur with that function.
  197.  
  198. All of the functions will perform correctly with IBM PC's or 
  199. close compatibles, but be aware that for several of the critical 
  200. timing functions direct screen writing is used to improve 
  201. performance.  Unless your machine addresses video memory in the 
  202. same manner as the IBM, a problem may exist.  The library was 
  203. written on a Tandy 1000 A  and has been run on several other 
  204. machines with complete success.
  205.  
  206. All functions beginning with dx are designed to support a daisy 
  207. wheel printer.  They were developed on a Epson printer that is 
  208. compatible with the DW-630.  All functions begining with gr are 
  209. designed to support the IBM graphics printer or compatible.  
  210. These were developed on a TANDY DMP 130.  
  211.  
  212. Those who are registered owners and have the source code will 
  213. find that only four functions need to be altered to support other 
  214. graphics systems.  These are the two dot routines (internal and 
  215. external) and the two functions to return the color of a pixel 
  216. (internal and external).  All other functions are based on these 
  217. to make conversion easier.  The author does not have access to a 
  218. Hercules system for this conversion.  A conversion to the EGA is 
  219. currently underway although access to an EGA system is very 
  220. limited for testing purposes.
  221.  
  222.  
  223.  
  224.                           Update Policy
  225.  
  226. It is the policy of Unicorn Software to provide one free update 
  227. for the library itself (not the source code which may be updated 
  228. for a small fee) and notification of one update beyond that.  If 
  229. the new library is registered for the update fee, then we will 
  230. start the process over again and you will again receive one free 
  231. update and one notification beyond that point.  This insures 
  232. users who register will always have access to the latest version 
  233. of the Tool Box.  Minor releases will be placed on bulletin 
  234. boards, but registered users will not be notified directly unless 
  235. they so request. (It is felt that most would prefer to use the 
  236. free update for a major release).  Currently the author places 
  237. copies of the Tool Box (major and minor releases) directly on the 
  238. following boards in the Seattle area.
  239.  
  240. 1.  Journey to Mars      (RBBS)  206  486-3136
  241. 2.  Night Shift          (RBBS)  206  488-0924
  242. 3.  Planet Claire        (RBBS)  206  783-8037
  243. 4.  PNW IBM user group   (RBBS)  206  343-7843
  244.  
  245.  
  246.  
  247. The author logs on with the name 'Dave Miller' on each of these 
  248. boards.
  249.  
  250. The most likely spot to find the author for feedback would be 
  251. Journey to Mars or Nightshift.
  252.  
  253.  
  254.  
  255.                         Programming Style
  256.  
  257.  
  258. The source code is written in standard K & R with one deviation.  
  259. The author prefers the opening and closing braces to line up so 
  260. instead of:
  261.  
  262.                if (i = 2) {
  263.                     printf("I = 2");
  264.                }
  265.  
  266. you will find:
  267.  
  268.                if (i = 2)
  269.                {
  270.                   printf("I = 2");
  271.                }
  272.  
  273. in the source code for the Tool Box.
  274.  
  275.  
  276.                     Declaration of Functions
  277.  
  278.  
  279. Most functions are either void or return int. It is not strictly 
  280. required to declare them prior to use.  It is GOOD PROGRAMMING 
  281. PRACTICE to declare all functions prior to use.  This practice 
  282. will avoid problems with the few functions which do return a 
  283. different value, such as a pointer to a window.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.                            Technical
  291.  
  292. This library was created using the following tools.
  293.  
  294.      Turbo C 1.00
  295.      Microsoft Link 3.51
  296.      MASM 4.0
  297.      Microsoft Library Manager 3.02
  298.  
  299.  
  300. The modules used and the order they should appear in the library 
  301. may be found by using LIB to create an LST file of the library.  
  302. If you register and wish to recompile for a different memory 
  303. model or compiler, this order should be preserved.
  304.  
  305. At present, a small bug exists in the endsound function.  It will 
  306. be best if you let background sound run its course, and not 
  307. attempt to stop it with this command.  This will be fixed in the 
  308. next major release ( Jan 1988 ).  Registered owners will 
  309. automatically receive the new source for this function with their 
  310. free update disk.
  311.  
  312. Revisions are possible in some functions in the next release.  
  313. Every possible effort will be used to maintain FULL 
  314. compatibility, but be aware that the calls to some window 
  315. functions and to the background sound functions may be altered 
  316. somewhat.  When using the Tool Box please keep this in mind if 
  317. you plan to upgrade.  It is anticipated the changes will not be 
  318. extensive and additional functions will be added wherever 
  319. possible rather than altering the existing functions.  The author 
  320. will preserve all current function calls intact in all releases 
  321. beyond this point.
  322.  
  323.                        Your First Program
  324.  
  325.  
  326.   Using the C Tool Box is essentially quite simple.  With Turbo C 
  327. you must specify any modules to be linked in your project file.  
  328. If they are not C files then the complete extension must be used.  
  329. For example suppose you wish to build a file 'mytest.exe' from 
  330. mytest.c and the C Tool Box library.  Your project file should be 
  331. in a form similar to the below:
  332.  
  333.  
  334.                              mytest
  335.                              CTB100.LIB
  336.  
  337.  
  338. When you are within the Turbo C environment, simply use Alt P to 
  339. indicate the project file name and then Alt R to build and run 
  340. your program.  You may also build your program from the command 
  341. line by typing:
  342.  
  343.                       TCC mytest CTB100.lib
  344.  
  345.  
  346. Either approach will build your program and link it with the C 
  347. Tool Box library.
  348.  
  349.  
  350. The demo program was built using the command:
  351.  
  352.                      TCC CTDEMO CTB100.LIB
  353.  
  354. There is a project file on the disk if you prefer to work within 
  355. the Turbo C environment.  The demo may be built by specifying 
  356. ctdemo as the file and ctdemo.prj as the project file.  Use ALT r 
  357. to run the program or ALT c to compile it.
  358.  
  359.                            The Future
  360.  
  361.  
  362. The next major release is planned for Jan., 1988.  Some 
  363. of the ideas being considered and/or worked on are:
  364.      
  365.      1.  Animation functions
  366.      2.  Data entry functions
  367.      3.  Menu functions (including pulldown)
  368.      4.  Additional window functions
  369.      5.  Additional sound functions
  370.      6.  Fonts - rewritting those left coded in C in assembler          
  371.          for speed and a true stroke font capability.  This was           
  372.          contained in the original Lattice C version;  The author
  373.          would like to restore it with full rotation, 
  374.          translation and scaling for the next major release.
  375.  
  376.      
  377. The author wishes to continue providing this library to users in 
  378. the form of shareware consistent with user support.  It has been 
  379. an enjoyable spare time project over the last year and a half. 
  380. The author feels shareware is an important element in today's 
  381. computer environment.
  382.  
  383. Please feel free to express your opinion on what you wish to see 
  384. made available.  Let us know!
  385.  
  386.                     Internal Global Variables
  387.  
  388.  
  389.    The library contains a series of global variables.  You 
  390. should not use these names in your programs unless you 
  391. specifically wish to reference that variable.  For example using 
  392. a variable named bdr1 in your program will result in a link error 
  393. at best or failure of the windowing functions that use border 1 
  394. at worst.  Below is a list of these variables and their internal 
  395. meanings to the library.
  396.  
  397. int       BLACK          the color black
  398. int       BLUE           the color blue
  399. int       GREEN          the color green
  400. int       CYAN           the color cyan
  401. int       RED            the color red
  402. int       MAGENTA        the color magenta
  403. int       BROWN          the color brown
  404. int       GRAY           the color gray
  405. int       GREY           the color gray
  406. int       WHITE          the color gray
  407. int       DARK_GRAY      the color dark gray
  408. int       DARK_GREY      the color dark gray
  409. int       LTBLUE         the color light blue
  410. int       LTGREEN        the color light green
  411. int       LTCYAN         the color light cyan
  412. int       LTRED          the color light red
  413. int       LTMAGENTA      the colorlight magenta
  414. int       LTBROWN        the color yellow
  415. int       YELLOW         the color yellow
  416. int       LTWHITE        the color light or bright white
  417.  
  418. int       NORMAL         the normal monochrome attribute
  419. int       UNDERLINE      the underline monochrome attribute
  420. int       REVERSE        the reverse video monochrome attribute
  421. int       BRIGHT         the highlighted monochrome attribute
  422. int       BLINK          monochrome blink bit indicator
  423.  
  424. int       v_start        starting address for video memory
  425. int       ct_mode_       current video mode
  426. int       ct_col_        current number of video columns
  427. int       ct_color_      indicates if color is allowed (1) or not 
  428.  
  429. BORDER    bdr1           a single line border for windows
  430. BORDER    bdr12          a border with a single vertical line and 
  431.                          double horizontal lines.
  432. BORDER    bdr21          a border with double vertical lines and 
  433.                          a single horizontal line
  434. BORDER    star           a border of "*" characters
  435. BORDER    dot            a border of "." characters
  436. BORDER    solid          a border of solid blocks ( char 219)
  437. BORDER    heart          a border of heart characters
  438. BORDER    space          a blank border of space characters
  439.  
  440.                          NOTE - The default border is a double
  441.                                 line.
  442.                                 BORDER is a pointer to a border. 
  443.                                 WINDOW is a pointer to a box, 
  444.                                 generally indicated by 'bp' in 
  445.                                 documentation.
  446.             
  447.  
  448. See the header CTB.H for additional variables and defines that 
  449. may be useful.
  450.  
  451.  
  452.                          
  453.                         Registration Form
  454.  
  455.    This library is distributed as shareware which simply means 
  456. you are free to copy, use and pass copies on to friends for 
  457. evaluation.  If you decide it is useful, you may register your 
  458. copy with the author.  Upon registration you will receive the 
  459. complete source code for the library and a copy of the manual on 
  460. disk.  This will consist of 3 disks.  In addition you will 
  461. receive the first update disk free and notification of any 
  462. further updates.  Major release updates are occuring about 3 
  463. times a year.
  464.  
  465. The current registration fee is $29.95   
  466.  
  467.  
  468. Name:             ______________________________________________
  469.  
  470. Computer Type:    ______________________________________________
  471.  
  472. Address:          ______________________________________________
  473.  
  474.                   ______________________________________________
  475.  
  476. City/State/Zip:   _________________________  ____  _____________
  477.  
  478. Library Version:  _CTB_1.00___________________________________
  479.  
  480. Compiler: (check 1)
  481.                   Turbo C ___  Microsoft C ___  other __________
  482.  
  483. More than one version may be requested.  Please add an update fee
  484. of $12.95 for each additional version.
  485.  
  486. Preprinted manual pages suitable for placement in a three ring 
  487. binder will be supplied for an additional $18.00.
  488.  
  489.                          User Statement
  490.  
  491. I realize that while the library may be freely given away to 
  492. third parties the source code is not public domain and I agree to 
  493. protect the authors code and not to pass it on to third parties.
  494.  
  495.  
  496. Signed:  ___________________________     Date:  ________________
  497.  
  498.  
  499.  
  500. Comments or additional information may be placed on the back of 
  501. this page.
  502.                       Function Descriptions
  503.  
  504. atsay     (row, col, fore, back, *string);
  505.           Print a string in color at row, column
  506.           back is for graphics. It's a dummy paramter in text 
  507.           mode.
  508.  
  509. bac16_4   (fore, back)
  510.           Sets 40 column text mode to use highlighted background 
  511.           colors
  512.  
  513. back16_8  (fore, back)
  514.           Sets 80 column text mode to use highlighted  background 
  515.           colors
  516.  
  517. backclr   (color)
  518.           Set the background color
  519.  
  520. backsnd   ()
  521.           Background sound function
  522.  
  523. beepsp    ()
  524.           Beeps the speaker with a tone similar to the DOS beep
  525.  
  526. blink16_4 (fore, back)
  527.           Sets 40 column text mode to normal blink attribute
  528.  
  529. blink16_8 (fore, back)
  530.           Sets 80 column text mode to normal blink attribute
  531.  
  532. boxfill   (x1, y1, x2, y2, color)
  533.           Draws a box and fills it with color (assembler)
  534.  
  535. boxtitle  (bp, position, col, title, fore, back)
  536.           Print a window title in the border
  537.  
  538. burble    (1/pitch, duration)
  539.           Plays an undescribable sound in the speaker. You have 
  540.           to try various numbers to see the variety.
  541.  
  542. button    ()
  543.           Returns joy stick button press status
  544.  
  545. circle    (rc, cc, radius, aspect_num, aspect_den, color)
  546.           Draws graphics cicrle with aspect ratio
  547.  
  548. cls       ()
  549.           Clear the screen and return mode and number of columns
  550.  
  551.  
  552.  
  553.  
  554. cls_clr   (fore, back)
  555.           Clears text screen (80 col), sets attributes and places 
  556.           the cursor in the 'home' position
  557.  
  558. CM_INCH   (cm)
  559.           Convert cm to inches
  560.  
  561. countch   (*string, char)
  562.           Returns # of times a char occurs in a string
  563.  
  564. ct_bkclr  (color)
  565.           Set background color
  566.  
  567. ct_char   (row, col, fore, back, char)
  568.           Write a character directly to the video buffer
  569.  
  570. ctinit    ()
  571.           Initializes video data for the windowing functions
  572.  
  573. ctone     (freq, duration)
  574.           Sounds a tone of given frequency and duration
  575.  
  576. ct_peek   (row, col)
  577.           Returns the WORD at row, col
  578.  
  579. ct_poke   (row, col, char)
  580.           Pokes a WORD at row, col
  581.  
  582. ctposit   (row, col)
  583.           Returns address of video memory byte at row, col
  584.  
  585. ct_sm     (mode)
  586.           Set the video mode
  587.  
  588. ct_str    (row, col, fore, back, *string)
  589.           Write a string directly to video buffer
  590.  
  591. ct_vstr   (row, col, fore, back, *string)
  592.           Write a string vertically directly to video memory
  593.  
  594. ct_wstr   (row, col, fore, back, *string, bp)
  595.           Write a string to video memory in a window
  596.  
  597. ct_wvstr  (row, col, fore, back, *string, bp)
  598.           Write a vertical string to video memory in a window
  599.  
  600. DEG_RAD   (degrees)
  601.           Convert degrees to radians
  602.  
  603.  
  604. delay     (millisecs)
  605.           Delay a number of ms, assumes 4.77 MHz clock
  606.  
  607. drawbox   (bp)
  608.           Draws a predefined box on the screen
  609.  
  610. dwarn2    ()
  611.           Issue a warning & exit if not DOS 2.00 or greater
  612.  
  613. dwarn3    ()
  614.           Issue a warning & exit if not DOS 3.00 or greater
  615.  
  616. dx120bs   ()
  617.           Backspace the DW printer 1/120th inch
  618.  
  619. dxback    ()
  620.           Select backwards printing on the DW printer
  621.  
  622. dxbi      ()
  623.           Select bidirectional printing
  624.  
  625. dxboldst  ()
  626.           Begin bold print
  627.  
  628. dxbs      ()
  629.           Send a backspace
  630.  
  631. dxbsend   ()
  632.           End bold/shadow printing
  633.  
  634. dxchwide  (number)
  635.           Set character width HMI (1/120ths inch)
  636.  
  637. dxclr1tab ()
  638.           Clear 1 tab
  639.  
  640. dxclrtab  ()
  641.           Clear all tabs
  642.  
  643. dxcr      ()
  644.           Send a carriage return
  645.  
  646. dxdefwid  ()
  647.           Set DW printer to default HMI
  648.  
  649. dxeject   ()
  650.           Eject paper
  651.  
  652.  
  653.  
  654. dxff      ()
  655.           Send a form feed
  656.  
  657. dxfor     ()
  658.           Select forward printing
  659.  
  660. dxhlf     ()
  661.           Send a half line feed
  662.  
  663. dxht      ()
  664.           Horizontal tab
  665.  
  666. dxinit    ()
  667.           Initialize the DW printer
  668.  
  669. dxlf      ()
  670.           Send a line feed
  671.  
  672. dxlinsp   (number)
  673.           Set line spacing in (n-1)/48 inch
  674.  
  675. dxlmarg   ()
  676.           Set left margin
  677.  
  678. dxpglen   (length)
  679.           Set page length
  680.  
  681. dxrhlf    ()
  682.           Send a reverse half line feed
  683.  
  684. dxrlf     ()
  685.           Send a reverse line feed
  686.  
  687. dxsetht   ()
  688.           Set a horizontal tab position
  689.  
  690. dxshast   ()
  691.           Start shadow printing
  692.  
  693. dxundend  ()
  694.           End underlined printing
  695.  
  696. dxundlst  ()
  697.           Begin underlining
  698.  
  699. dxuni     ()
  700.           Select unidirectional printing
  701.  
  702.  
  703.  
  704. endsound  ()
  705.           Uninstall the sound timer interrupt and turn background 
  706.           music off
  707.  
  708. equip     ()
  709.           Returns a word indicating installed equipment
  710.  
  711. flagdec   ()
  712.           Decrements mouse cursor flag by one
  713.           
  714. forward   (pixels)
  715.           Move the turtle forward a number of pixels
  716.  
  717. GAL_LT    (gallons)
  718.           Convert gallons to liters
  719.  
  720. gcomtype  ()
  721.           Returns a byte indicating the computer type in use
  722.  
  723. gcurpos   (row, col, page)
  724.           Return current cursor position
  725.  
  726. getatch   (page)
  727.           Returns char and attribute at current cursor position
  728.  
  729. getbcnt   (which_button)
  730.           Returns the count of mouse button presses
  731.  
  732. getbrcnt  (which_button)
  733.           Returns mouse button releases
  734.  
  735. getbstat  ()
  736.           Returns current mouse button status
  737.  
  738. getchne   ()
  739.           Return keyboard character with no echo
  740.  
  741. getctype  (start, end, page)
  742.           Return the current cursor start & end lines and page
  743.  
  744. getcurp   (&row, &col)
  745.           Return cursor position
  746.  
  747. getcurps  (page, &row, &col)
  748.           Returns cursor position on a specified page
  749.  
  750. getdmaj   ()
  751.           Return the DOS major version number
  752.  
  753.  
  754. getdmin   ()
  755.           Return the DOS minor version number
  756.  
  757. getdver   ()
  758.           Return the DOS version number
  759.  
  760. gethpos   ()
  761.           Returns the current mouse horizontal position
  762.  
  763. getkey    ()
  764.           Destructive read of keyboard buffer
  765.  
  766. getkeycd  ()
  767.           Return keycode - waits for key stroke
  768.  
  769. getmode   ()
  770.           Returns the current video mode
  771.  
  772. getpage   ()
  773.           Returns the current video page
  774.  
  775. getscode  ()
  776.           Returns scan code for key stroke, waits for key
  777.  
  778. getstate  ()
  779.           Get video state, mode, width, page into register struct
  780.  
  781. get_str   ()
  782.           Get user string and replace CR with \0
  783.  
  784. getvpos   ()
  785.           Returns the mouse current vertical position
  786.  
  787. gliss     (start_freq, end_freq, rate)
  788.           sounds a glissando through the speaker
  789.  
  790. GM_OZ     (grams)
  791.           Convert grams to ounces
  792.  
  793. gothic    (char, row, col, color)
  794.           Writes a gothic character to the graphics screen
  795.  
  796. hollow    (char, row, col, color)
  797.           Writes an outline character to the graphics screen
  798.  
  799. INCH_CM   (inches)
  800.           Convert inches to cm
  801.  
  802.  
  803.  
  804. indexch   (*string, char)
  805.           Return the first position of a character in a string
  806.  
  807. indexr    (*string, char)
  808.           Return the rightmost position of char in string
  809.  
  810. iskey     ()
  811.           Returns non-0 if key in buffer / 0 if no key
  812.  
  813. kbstat    ()
  814.           Returns the keyboard status byte
  815.  
  816. keystat   ()
  817.           DOS interrupt to return keyboard status byte
  818.  
  819. KG_LB     (kilograms)
  820.           Convert kilograms to pounds
  821.  
  822. KM_MI     (kilometers)
  823.           Convert kilometers to miles
  824.  
  825. LB_KG     (pounds)
  826.           Convert pounds to kilograms
  827.  
  828. lhjoystk  ()
  829.           Return the current horizontal pos, of left joystick
  830.  
  831. lightpen  (&row, &col, &rasline, &ras_col)
  832.           Read the lightpen position
  833.  
  834. line      (x1, y1, x2, y2, color)
  835.           Draw a graphics line
  836.  
  837. lprintf   (*string)
  838.           Print a string to the line printer
  839.  
  840. lputch    (char)
  841.           Send a character to the printer
  842.  
  843. lrotate   (yc, xc, ys, xs, ye, xe, 3, angle)
  844.           Draw a rotated line around a center point
  845.  
  846. lsthpos   (which_button)
  847.           Return last mouse horiz. position when button pressed
  848.  
  849. lsthrpos  (which_button)
  850.           Last mouse horiz. position when button released
  851.  
  852.  
  853.  
  854. lstvpos   (which_button)
  855.           Last mouse vertical pos. when button pressed
  856.  
  857. lstrvpos  (which_button)
  858.           Last mouse vertical pos. when button release
  859.  
  860. LT_GAL    (liters)
  861.           Conver liters to gallons
  862.  
  863. lvjoystk  ()
  864.           Return the current vertical pos. of left joystick
  865.  
  866. M_YD      (meters)
  867.           Convert meters to yards
  868.  
  869. makebdr   (bp, type)
  870.           Sets a border type for a window/box
  871.  
  872. makebox   (row, col, height, width, bfore, bback, ffore, fback)
  873.           Defines a new box/window and returns a pointer to it
  874.  
  875. memsize   ()
  876.           Return memory size using int86 call
  877.  
  878. mgun      ()
  879.           Makes a machine gun tye sound through the speaker
  880.  
  881. MI_KM     (miles)
  882.           Convert miles to kilometers
  883.  
  884. moveto    (row, col)
  885.           Move the turtle to an absolute position
  886.  
  887. mreset    ()
  888.           Checks to see if mouse is installed
  889.  
  890. msize     ()
  891.           Returns the number of K Bytes of memory installed
  892.  
  893. note      (voice, octave, note, volume)
  894.           Set a musical note for TANDY 1000 voice
  895.  
  896. OZ_GM     (ounces)
  897.           Convert ounces to grams
  898.  
  899. paint     (row, col, color, border_color)
  900.           fill a bounded region with color
  901.  
  902.  
  903.  
  904. palette   (a, b, c)
  905.           Change color set for graphics modes
  906.           a = palette (0-3)
  907.           b = 4 for normal colors / 5 for alternate color set
  908.           c = background color
  909.  
  910. pcurpos   (row, col, page)
  911.           Places cursor to location
  912.  
  913. pencolor  (color)
  914.           Defines turtle pen color
  915.  
  916. pendown   ()
  917.           Places trutle pen on screen to draw
  918.  
  919. penup     ()
  920.           Lifts turtle pen off screen 
  921.  
  922. play      (note, octave, time)
  923.           plays a foreground tone in the speaker
  924.  
  925. point     (row, col, color)
  926.           Lights a single graphics pixel
  927.  
  928. prtbs     ()
  929.           Send backspace to the graphics printer
  930.  
  931. prtbuzz   ()
  932.           Sound the printer bell
  933.  
  934. prtcan    ()
  935.           Cancel and clear the printer buffer
  936.  
  937. prtcomof  ()
  938.           Turn off compressed print
  939.  
  940. prtcomon  ()   
  941.           Turn on compressed print mode
  942.  
  943. prtcr     ()
  944.           Send a carriage return to the graphics printer
  945.  
  946. prtdubof  ()
  947.           Turn off double print mode
  948.  
  949. prtdubon  ()
  950.           Turn on double print mode
  951.  
  952.  
  953.  
  954. prtempof  ()
  955.           Turn off emphasized print mode
  956.   
  957. prtempon  ()
  958.           Turn on emphasized print mode
  959.  
  960. prtsec    ()
  961.           Send an ESC code to the printer
  962.  
  963. prtff     ()
  964.           Send a form feed to the graphics printer
  965.  
  966. prtlf     ()
  967.           Send a line feed
  968.  
  969. prttab    ()
  970.           Send atab to the graphics printer
  971.  
  972. prtwidof  ()
  973.           Turn off the double width character mode
  974.  
  975. prtwidon  ()
  976.           Turn on the double width character mode
  977.  
  978. RAD_DEG   (radians)
  979.           Convert radians to degrees
  980.  
  981. raschar   (char, ULR, ULC, hmag, vmag, color)
  982.           Uses the internal character font descriptions to 
  983.           display characters at larger sizes
  984.      
  985. rdhcount  ()
  986.           Reads current mouse horizontal motion counter
  987.  
  988. rdvcount  ()
  989.           Reads current mouse vertical motion counter
  990.  
  991. readkey   ()
  992.           Destructive return of ASCII and scan codes for key 
  993.  
  994. rect      (ULR, ULC, LRR, LRC, color)
  995.           Draw a filled rectangle
  996.  
  997. rect1     (ULR, ULC, LRR, LRC, bdr_clr, rect_clr)
  998.           Draw a flled rectangle bounded by a single pixel border
  999.  
  1000. rect2     (ULR, ULC, LRR, LRC, bdr_clr, rect_clr)
  1001.           Draw a flled rectangle bounded by a double pixel border
  1002.  
  1003.  
  1004. redalert  ()
  1005.           Plays a red alert sound through the speaker
  1006.  
  1007. replacech (*string, old_char, new_char)
  1008.           Replaces ALL occurences of char in string
  1009.  
  1010. resbox    (bp)
  1011.           Removes a window/box from the screen and restores video
  1012.  
  1013. rhjoystk  ()
  1014.           Return right joystick horizontal position
  1015.  
  1016. rotate    (yc, xc, x, y, angle)
  1017.           rotate a point around a given center point
  1018.  
  1019. rvjoystk  ()
  1020.           Return right joystick vertical position
  1021.  
  1022. savebox   (bp)
  1023.           Saves the memory where a window/box will be drawn
  1024.  
  1025. scankey   ()
  1026.           Returns scan and ASCII codes (non-destructive)
  1027.  
  1028. script    (char, row, col, color)
  1029.           Draw a simulated handwritten character on the graphics 
  1030.           screen
  1031.  
  1032. scrolldn  (up_l_row, up_l_col, low_r_row, low_r_col, fore, back, 
  1033.           num_rows)
  1034.           Scroll a bios window down
  1035.  
  1036. scrollup  (up_l_row, up_l_col, low_r_row, low_r_col, fore, back, 
  1037.           num_rows)
  1038.           Scroll a bios window up  
  1039.  
  1040. setatten  (voice, level)
  1041.           Sets attenuation level on Tandy 1000 sound chip
  1042.  
  1043. setcallm  (mask, address)
  1044.           Define a mouse subroutine mask
  1045.  
  1046. setcur    (h_hot, v_hot, cursor)
  1047.           Define and pass a mouse graphics cursor
  1048.  
  1049. setcurp   (row, col)
  1050.           Sets the cursor to location
  1051.  
  1052.  
  1053. setcurps  (page, row, col)
  1054.           Sets position of cursor on the page
  1055.  
  1056. setcurt   (start, end)
  1057.           Sets the cursor type parameters
  1058.  
  1059. setcurtp  (start, end)
  1060.           Sets start and end lines for cursor
  1061.  
  1062. setfreq   (voice, freq)
  1063.           Set Tandy voice frequency
  1064.  
  1065. sethor    (min, max)
  1066.           Sets mouse min and max positions
  1067.  
  1068. setpage   (page)
  1069.           Set the current visual page number
  1070.  
  1071. set_pal   (color_set)
  1072.           Selects either color set 0 or 1 for graphics
  1073.  
  1074. setpal    (0/1)
  1075.           Selects a palette for graphics modes
  1076.  
  1077. setpos    (hor, ver)
  1078.           Set mouse cursor postion
  1079.  
  1080. setsound  ()
  1081.           enables the background sound interrupt and uses notes 
  1082.           in array melody and timing in array beat to produce 
  1083.           background sound
  1084.  
  1085. settxtc   (type,screen_mask/first_line, cur_mask/lst_line)
  1086.           Select and define mouse text cursor
  1087.  
  1088. setver    (min, max)
  1089.           Set max and min vertical mouse positions
  1090.  
  1091. sm        (mode)
  1092.           Set the video mode
  1093.  
  1094. smode     (mode)
  1095.           set video moe using int86
  1096.  
  1097. soundoff  ()
  1098.           Turn off Tandy sound chip
  1099.  
  1100. soundon   ()
  1101.           Turn on the Tandy sound chip
  1102.  
  1103. spalreg   (reg#, color)
  1104.           Set the palette register values (Tandy & EGA only)
  1105.  
  1106. spratio   (hor, ver)
  1107.           Set mouse movement ratios
  1108.  
  1109. str_cent  (*string, *destination, width)
  1110.           Center a string within width
  1111.  
  1112. strclr    (fore, back, *string)
  1113.           C function to write a string in color
  1114.  
  1115. strdel    (*string, start, number)
  1116.           Delete a substring from a string
  1117.  
  1118. strpad    (*string, number)
  1119.           Add spaces to the left of a string
  1120.  
  1121. strtolow  (*string)
  1122.           Convert a string to all lower case
  1123.  
  1124. strtoup   (*string)
  1125.           Convert a string to all upper case
  1126.  
  1127. tcos      (angle)
  1128.           return 2 digit value of cosine for whole degrees - 
  1129.           operates faster for graphics plotting
  1130.  
  1131. tone      (freq, time_in_ms)
  1132.           play a tone - time assumes 4.77 MHz clock
  1133.  
  1134. tsin      (angle)
  1135.           return 2 digit value of sin for whole degrees - 
  1136.           operates faster for graphics than does the sin function
  1137.  
  1138. turnleft  (angle)        
  1139.           Turns the turtle heading left
  1140.  
  1141. turnright (angle)
  1142.           Turns the turtle heading right
  1143.  
  1144. usrfont   (char, ULR, ULC, hmag, vmag, color, font#)
  1145.           Allows user to select from predetermined fonts the 
  1146.           style of character to display
  1147.  
  1148. vbar3d    (base, height, col, width, depth, color, outline_color)
  1149.           3d bar graph plot function
  1150.  
  1151.  
  1152.  
  1153. wac       (char, color/attribute, xor_flag)
  1154.           Write a character and attribute/color using BIOS call
  1155.  
  1156. waitkey   ()
  1157.           Pauses and waits for key stroke if none in buffer
  1158.  
  1159. watch     (page, num_chars, char, fore, back)
  1160.           Writes character(s) in color using BIOS call
  1161.  
  1162. wch       (page, num_chars, char, color)
  1163.           Writes char(s) to page (text mode) in color (graphics 
  1164.           mode)
  1165.  
  1166. wchtty    (char, fore)
  1167.           Writes character using tty BIOS mode, color if graphics 
  1168.           mode in use
  1169.  
  1170. wco       (char, color)
  1171.           Write character only (color is active in graphics, 
  1172.           dummy parameter in text modes)
  1173.  
  1174. wgets     (bp, row, col, len)
  1175.           Return a string that exists inside a window
  1176.  
  1177. w_hline   (row, col,fore, back, char, width)
  1178.           Draw a horizontal line of character
  1179.  
  1180. wnoise    (low_freq, high_freq, duration)
  1181.           Produces white noise over a specified freq range
  1182.  
  1183. wputs     (bp, str, row, col)
  1184.           Puts s string to a window using BIOS
  1185.  
  1186. wtty      (char, color)
  1187.           Write character in TTY mode, color is only active in 
  1188.           graphics modes, in text modes it is a dummy parameter
  1189.  
  1190. w_hline   (row, col, fore, back, ch, width)
  1191.           Draw a horizontal line of character
  1192.  
  1193. w_vline   (row, col, fore, back, char, height)
  1194.           Draws a vertical string of character
  1195.  
  1196. YD_M      (yards)
  1197.           Convert yards to meters
  1198.  
  1199.  
  1200.  
  1201.  
  1202.  
  1203.  
  1204.  
  1205.                            Appendix A
  1206.  
  1207.  
  1208.  
  1209.  
  1210.  
  1211.    This section of the manual is a detailed description of the 
  1212. functions.  It includes a description of the function, a sample 
  1213. call from C, a sample program or program fragment using the 
  1214. function and any returns from the function.  Included also are 
  1215. any limits, peculiarities or other information about the 
  1216. functions required for effective use in programming.
  1217.  
  1218.                              atsay                     
  1219.  
  1220.  
  1221.  
  1222. This function is similar to the dBASE function of the same name 
  1223. in that it allows the user to print, in color, a string at a 
  1224. specified location on the screen.
  1225.  
  1226.  
  1227. Call:
  1228.           atsay(row, col, fore, back, *string)
  1229.  
  1230.           row       = the starting row for the string
  1231.           col       = the starting column for the string
  1232.           fore      = the foreground color of the string
  1233.           back      = the background color of the string
  1234.           string    = the string to be printed on the screen
  1235.  
  1236. Example:
  1237.           main()
  1238.           {
  1239.                /* sm(4); */
  1240.                atsay(5, 10, 3, 2, "Testing");
  1241.           }
  1242.  
  1243.           This program will print the string "Testing" on the           
  1244.           screen in color 3, starting at row 5 column 10. If in 
  1245.           graphics mode (remove the comments) the background 
  1246.           color will be color 2, for text mode this parameter is 
  1247.           a dummy parameter.
  1248.  
  1249.  
  1250. Return:
  1251.           None
  1252.  
  1253.  
  1254. Caveats:
  1255.           Background color is only active in graphics modes.  For 
  1256.           text modes it is a dummy parameter.  For writting with 
  1257.           a background color in text modes use the watch 
  1258.           function.
  1259.           Be sure the string parameters lie within the screen 
  1260.           boundries.
  1261.  
  1262.  
  1263.  
  1264.  
  1265.  
  1266.  
  1267.  
  1268.    This ends the Board version of the manual.
  1269.  
  1270.  
  1271.  
  1272.  
  1273.  
  1274. The full manual will be sent with all library source code to all 
  1275. registered owners of the C Tool box Library.  There simply is not 
  1276. enough room in a bulletin board sized file.
  1277.  
  1278. This section of the manual is an early version.  The final manual 
  1279. will contain complete descriptions of all aspects of the tool 
  1280. Box.  It is available in two disk formats.  One suitable for 
  1281. printing from DOS and one in WordStar format.  It is also 
  1282. available in the form of preprinted pages suitable for a three 
  1283. ring binder.
  1284.  
  1285.  
  1286. The  following is included since the full manual is not with this 
  1287. file.
  1288.  
  1289.  
  1290. BACKGROUND SOUND FUNCTIONS INFORMATION
  1291.  
  1292. The numbers for the musical notes are listed below for the octave 
  1293. starting with middle C:
  1294.  
  1295. C    C#   D   D#   E    F    F#    G    G#    A   A#    B
  1296. 24   25   26  27  28   29    30    31   32    33  34    35
  1297.  
  1298. The note 100 may be used for rests.
  1299.  
  1300. Timing for the notes is in timer ticks (18.2 per second).
  1301.  
  1302. See the full manual for further details.
  1303.  
  1304. Place the notes in an array called melody[] and the timing count 
  1305. in an array called beat[], see ctdemo.c for an example.  Other 
  1306. songs may be defined with notes and timing in different arrays 
  1307. but these will have to be copied into the melody and beat arrays 
  1308. before activation the background sound function.  A future 
  1309. release will pass a pointer to the desired array.
  1310.   eat arrays 
  1311. before activation the background sound function.  A future 
  1312. release will pass a pointer to the desire